Developer CD Series 1994 June: Reference Library/Dev.CD Jun 94.toast/Technical Documentation/Mac Tech Notes (DocViewer)/QuickTime/QT05-Component Mgr 3.0/QT05-Component Mgr 3.0

Text File | 1994-04-27 | 90.9 KB | 233 lines | [ONLN/HLX2]

QT 05 - Component Manager version 3.0
QuickTime    & Dave Radcliffe    March 1994
This note contains information regarding the version of the Component Manager that shipped with QuickTime 1.6 and the changes necessary to support native PowerPC components.
Topics
• QuickTime 1.6 and Component Manager 3.0
• Native PowerPC components
Introduction
The Component Manager in QuickTime 1.6.x and for the Power Macintosh (PowerPC) release has some new features. It has added the ability to automatically resolve conflicts between different versions of the same component. It will ensure that only the most recent version of a given component is actually registered. The Component Manager now supports Icon Suites for a component, so a component’s icon no longer has to be just black and white. In addition, the Component Manager can support code written in the native format of the PowerPC.
The result returned for the Gestalt selector gestaltComponentMgr will be 3, indicating version number 3 of the Component Manager. This is the version being discussed in this note. To insure that you have the features discussed here, check that version 3 is installed.
For support of the Power Macintosh, the Component Manager has been extended to allow use of native PowerPC components. When the Component Manager loads a native component on the Power Macintosh, it calls uses the Code Fragment Manager and calls GetMemFragment and then later CloseConnection when it unloads your code resource (specified in a ComponentPlatformInfo). This is how the Component Manager supports a native code fragment.
A component can support multiple platforms such as the 68K and PowerPC. Existing 68K code is always supported on the Power Macintosh through emulation. But you can also have native PowerPC code for your component to support better performance. The Component Manager will allow you to create a component that contains both code formats, so that you can support all platforms with a single component. The Component Manager also was extended in a way that allows for native PowerPC only components (without any 68K code support).
Extended ComponentResource
The ComponentResource data structure (the 'thng' resource) has been extended. These extensions define additional information about the component. The complete data structure is shown below. The first portion is the same as the existing ComponentResource, with the new fields added at the end. The Component Manager determines if it is present by examining the size of the 'thng' resource.
struct ExtComponentResource {
    ComponentDescription    cd;            /* Registration parameters */
    ResourceSpec     component;            /* resource where Component code                                is found */
    ResourceSpec    componentName;        /* name string resource */
    ResourceSpec    componentInfo;        /* info string resource */
    ResourceSpec    componentIcon;        /* icon resource */
    /* new data for Component Manager version 3 */
    long        componentVersion;        /* version of Component */
    long        componentRegisterFlags;    /* flags for registration */
    short        componentIconFamily;        /* resource id of Icon Family */
    long        count;                /* elements in platformArray */
    ComponentPlatformInfo platformArray[1];
};
componentVersion
The componentVersion field contains the version number of the component. This should be identical to the value returned by GetComponentVersion. For convenience, if this value is set to 0, the component is called to get the version. This is useful during development. The version number stored in the ComponentResourceExtension is used by the Component Manager to avoid having to load and call the component to retrieve the component’s version during startup.
componentRegisterFlags

The componentRegisterFlags allow you to define additional register information. These flags are discussed below.
/* Component Resource Extension flags */
componentDoAutoVersion             = (1<<0)
componentWantsUnregister            = (1<<1)
componentAutoVersionIncludeFlags        = (1<<2)
componentHasMultiplePlatforms        = (1<<3)
The componentDoAutoVersion flag tells the Component Manager that you want your component registered only if there is no later version available. If there is an older version of the component installed, it will be unregistered. If an older version of the same component attempts to register after you, it will be immediately unregistered. Further, if a newer version of the same component registers after you, you will automatically be unregistered. Using the automatic version control feature of the Component Manager allows you to make sure that only the most recent version of your software is running on a given machine, regardless of how many versions may be installed.
The componentWantsUnregister flag indicates that your component wants to be called when it is unregistered. This is useful if your component allocates global memory at register time, for example. The prototype of the unregister message is identical to the register message. If your component has never been opened, its unregister message is not be called. The routine selector for unregister is given below.
kComponentUnregisterSelect         = -7
The componentAutoVersionIncludeFlags flag tells the Component Manager to use the component flags as criteria for its component search. If a component wants automatic version control, the Component Manager has to search for similar components. Normally, the Component Manager searches only for another component using the type, subType, and manufacturer fields of a ComponentDescription record. This flag tells the Component Manager to include the componentFlags in its search.
The componentHasMultiplePlatforms flag indicates that your component contains multiple versions of the code for different platforms. If you plan on supporting the PowerPC native code format, then you need to use the ComponentPlatformInfo within the component resource structure. Then set this bit in the componentRegisterFlags field. If this bit is not set then the code is assumed to be 68K format. Without this flag being set, the Component Manager will ignore any ComponentPlatformInfo.
componentIconFamily
Finally, the componentIconFamily field allows you to provide the resource ID of a System 7 Icon Suite. If this field is 0, it indicates that there is no icon suite.
count
This is the number of elements contained in the ComponentPlatformInfo array.
platformArray
This is an array of elements that describe the code to be used for different platforms. If the platform is for 68K, then the information within this element is a copy from the componentFlags of the ComponentDescription and ResourceSpec of the original ComponentResource structure. This insures backwards compatibility with older Component Managers. If the component contains native code support for the PowerPC, then an element of the array will contain the information about its componentFlags, resource type, and resource ID.
The platformType field is a value that represents which platform the component code is to support. The Gestalt result for selector gestaltSysArchitecture will be matched with the value in platformType of the ComponentResource. If a match is found, then that code is used to support the given platform.
    gestalt68k        = 1,            /* Motorola MC68K architecture */
    gestaltPowerPC    = 2,            /* IBM PowerPC architecture */
struct ComponentPlatformInfo
{
    long            componentFlags;    /* flags of Component */
    ResourceSpec        component;        /* resource where Component code                                is found */
    short            platformType;        /* gestaltSysArchitecture result */
};
Component Manager version 3 routines
GetComponentIconSuite
GetComponentIconSuite returns an Icon Suite for the given component. This call works only under System 7 or later. If called on System 6, it returns an error. If the component doesn’t have an Icon Suite but does have a Component Icon (as returned by GetComponentInfo), GetComponentIconSuite creates an Icon Suite containing just the black-and-white Component Icon. In this way, you can use GetComponentIconSuite whether or not a component has an Icon Suite.
pascal OSErr GetComponentIconSuite(Component aComponent, Handle *iconSuite)
aComponent    Component ID, retrieved with FindNextComponent.
iconSuite    Pointer to the Icon Suite you will receive.
RegisterComponent
RegisterComponentResource
RegisterComponentResourceFile
The only change made to these routines was to modify the use of the global parameter. The upper byte now contains the platform ID to be used by the component being registered. This change is necessary because these calls do not have access to the ComponentResource which contains the ComponentPlatformInfo. If the upper byte of the global parameter is zero, then the platform is assumed to be the platform68k.
How to create a PowerPC ComponentResource
The basics step for running on a Power Macintosh with a native component are:
•  Create component code fragment with native PowerPC code
•  Main entry point to code is a mixed mode routine descriptor
•  Package component code fragment as a resource
•  If you supply an interface for the component to be called directly, then for PowerPC code to
   call your component you must provide custom glue to make the call.
•  Create the extended 'thng' resource using the ComponentPlatformInfo
Each of these steps are discussed in more detail below:
Creating the component code fragment
The first step in creating a native PowerPC component is to port your code.  For complete details on porting to PowerPC, see Inside Macintosh: PowerPC System Software.  Especially important for the following discussion is an understanding of the Mixed Mode and Code Fragment Managers.
Like other code ported for PowerPC, anytime your code uses a callback function (ProcPtr), it must be converted to a UniversalProcPtr.  But unlike callbacks defined by the system, callbacks to your component have their own function prototypes.  With the exception of some callbacks defined for QuickTime components, there are no system supplied function prototypes or UniversalProcPtrs, so you must create these yourself.
If, in response to a request code, your component dispatches to internal functions using CallComponentFunction or CallComponentFunctionWithStorage, then this is a place where you must use a UniversalProcPtr.
Suppose your component currently responds to an open request as follows:
    switch (params->what)
    {
        case kComponentOpenSelect:    /* Open request */
        {
        result = CallComponentFunctionWithStorage (storage, params, MyOpen);
        break;
        }
MyOpen is an internal function callback, so you must create a RoutineDescriptor/UniversalProcPtr for it.  MyOpen is declared as follows:
pascal ComponentResult MyOpen (Handle storage, ComponentInstance self);
The first step is to create a ProcInfo value for this function:
enum {
   uppMyOpenProcInfo = kPascalStackBased
    | RESULT_SIZE(SIZE_CODE(sizeof(ComponentResult)))
    | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(Handle)))
    | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(ComponentInstance)))
};
Next you must update your source to build a UniversalProcPtr and use it.  You could use NewRoutineDescriptor for this purpose, but the disadvantage is that creates a heap object which your component must dispose of properly.
An alternate approach is to declare a global RoutineDescriptor (global variables are not a problem for a native PowerPC component, since a code fragment automatically has global variables):
#ifdef powerc
RoutineDescriptor MyOpenRD = BUILD_ROUTINE_DESCRIPTOR (uppMyOpenProcInfo, MyOpen);
#endif
If you want your code to be compilable for both 68K and PowerPC, using the Universal Interfaces, then to avoid a lot of conditional compilation, the following macros may be useful:
#ifdef powerc
#define CallComponentFunctionWithStorageUniv(storage, params, funcName) \
   CallComponentFunctionWithStorage(storage, params, &funcName##RD)
#define CallComponentFunctionUniv(params, funcName) \
   CallComponentFunction(params, &funcName##RD)
#define INSTANTIATE_ROUTINE_DESCRIPTOR(funcName) RoutineDescriptor funcName##RD = \
   BUILD_ROUTINE_DESCRIPTOR (upp##funcName##ProcInfo, funcName)
#else
#define CallComponentFunctionWithStorageUniv(storage, params, funcName) \
   CallComponentFunctionWithStorage(storage, params, (ComponentFunctionUPP)funcName)
#define CallComponentFunctionUniv(params, funcName) \
   CallComponentFunction(params, (ComponentFunctionUPP)funcName)
#endif
These macros, exactly analogous to CallComponentFunction and CallComponentFunctionWithStorage, generate the appropriate code when compiled for 68K and PowerPC.  Note that the PowerPC macro expansion depends on the global RoutineDescriptor name being FuncNameRD, i.e. the name of the function with RD appended.  The INSTANTIATE_ROUTINE_DESCRIPTOR macro can be used for that purpose:
#ifdef powerc
INSTANTIATE_ROUTINE_DESCRIPTOR(MyOpen);
#endif
This is identical to the declaration of MyOpenRD earlier, but simplifies the editing.
With all the conditional stuff out of the way, then the original code can simply be updated by replacing CallComponentFunctionWithStorage with CallComponentFunctionWithStorageUniv:
    switch (params->what)
    {
       case kComponentOpenSelect:        /* Open request */
       {
        result = CallComponentFunctionWithStorageUniv(storage, params,MyOpen);
        break;
       }
Repeat the above steps for all internal component dispatches you make.
Setting the main entry point
Lastly, you must set up the entry point into your component correctly.  Unlike a 68K code resource, a PowerPC code fragment (which your component will be) has a well defined entry point.  The Component Manager, rather than just jumping to the start of the code resource, will call the main entry point, as defined when linking, instead.
But the Component Manager is 68K code, which means your main entry point must be a RoutineDescriptor.  You can set that up as follows:
pascal    ComponentResult    main    (ComponentParameters    *params,
                     Handle          storage);
#ifdef powerc
enum {
    uppMainProcInfo = kPascalStackBased
        | RESULT_SIZE(SIZE_CODE(sizeof(ComponentResult)))
        | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ComponentParameters *)))
        | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Handle)))
};
RoutineDescriptor MainRD = BUILD_ROUTINE_DESCRIPTOR(uppMainProcInfo, main);
#endif
When you link the component, you must then specify MainRD as the entry point.
Note:    Your development environment may issue a warning because your main entry point is in a data section, not a code section.  You may ignore the warning.
Note:    If your code is dependent on C or C++ runtime initializations, then your main entry point would be __start or __cplusstart, respectively, rather than main.  Modify the previous example accordingly.
Note: Some components rely on a “fast dispatching” mechanism for calling component functions.  This mechanism is dependent on the 68K architecture and is unsupported for native components, although it will work for emulated components running on the Power Macintosh.
Note: In all these modifications for PowerPC, the most difficult thing to get right is the ProcInfo value.  It’s very easy to make a “cut and paste” error, or get a type wrong (short instead of short *).  If your component is crashing the first thing to check (and check and check and check!) are the ProcInfo values.
Packaging the PowerPC component into a resource
PowerPC development tools create your PowerPC code in a code fragment in the data fork of the file.  Your component code must be a resource (the resource type and id are specified in the 'thng' resource described below).  You can use the MPW Rez “read” command to read from the data fork into a resource.  For example:
    read 'mycp' (130) mycomponent.pef;
reads the code fragment from the file mycomponent.pef and creates the resource 'mycp'(130).
Providing an interface to the component
If you wish your component to be called directly, you must also supply an interface so callers know how to call it.  For standard functions, such as Open, Close, Version, etc., this is not a problem as the Component Manager supplies functions to do this for you.  Nor is this a problem if you are writing QuickTime components, as QuickTime supplies standard interfaces and libraries for calling components.
But one of the advantages of the Component Manager is it lets you define your own routines with their own parameter lists, and for these routines you must supply an interface.  Typically, for 68K this involved providing callers an interface file with function prototypes for your calls and inline 68K assembly to actually make the call.
Obviously, the inline 68K code is a problem for a native PowerPC caller, so you must provide glue to accomplish the same thing.  The following discussion also applies to calling a 68K component from PowerPC code.  The interface is the same, either way.
To take the example for Inside Macintosh: More Macintosh Toolbox, page 6-30, you might have a call like:
pascal ComponentResult DrawerSetup (ComponentInstance myInstance, Rect *r) =
    ComponentCallNow (kDrawerSetUpSelect, 4);
ComponentCallNow is a macro that expands to inline 68K code that pushes additional parameters and then executes an A-trap to call the Component Manager.
The first thing when using the new Universal Headers, is that the definition of ComponentCallNow has changed slightly.  The above declaration would change to:
pascal ComponentResult DrawerSetup (ComponentInstance myInstance, Rect *r)
    ComponentCallNow (kDrawerSetUpSelect, 4);
The only difference in this declaration is that the ‘=’ character is missing.  This is necessary to allow the code to compile for both 68K and PowerPC.
For 68K code, ComponentCallNow continues to expand to inline 68K code, but for PowerPC, the ComponentCallNow macro expands to nothing, which means the above declaration reduces to:
pascal ComponentResult DrawerSetup (ComponentInstance myInstance, Rect *r) ;
You must now supply glue for DrawerSetup that does the same thing on PowerPC as the 68K inlines would do.
The strategy here is to mimic what 68K code calling your component would do.  Namely, push a bunch of parameters on the stack, then call the component.  You do that by building a struct that looks like the parameters as they would appear on the 68K stack.  Each call will require a different struct because each call can have different parameters.
Use the struct below (DrawerSetupGluePB) as a template.  The first three fields, componentFlags, componentParamSize, and componentWhat are required, as is the last field, which is the component instance.
componentFlags is unused and should be zero.
componentParamSize is the size, in bytes, of the parameters to the call, not counting the component instance.  This is the same number that is passed as the second parameter in a ComponentCallNow macro call, and should be the same as the size of the params struct, discussed below.
componentWhat is the selector for your component call.  Its the same as the first parameter to a ComponentCallNow macro call.
The params field is a separate struct that exactly mirrors your parameters.   This must be customized for your call.  A separate struct is used here because it simplifies the sizeof calculation for the componentParamSize field.  Parameters in this struct are specified in reverse order from the parameter list.

Note:    Remember that the struct mirrors 68K stack alignment, not 68K struct alignment.  This means that byte parameters, e.g. char or Boolean, get passed as two bytes, not one. The struct must mirror that fact, so you must declare byte fields to be a byte field followed by a pad byte field and take it into account in your parameter size calculations.

Once you have the struct, initialize it as shown in the example, and call the component via CallUniversalProc with the CallComponentUPP.  CallComponentUPP is declared for you and is part of the InterfaceLib.  You don't need to do anything special to use it.
uppCallComponentProcInfo should have been in the interfaces, because the call is always the same, but it's not, so it's defined below.
enum {
    uppCallComponentProcInfo = kPascalStackBased
        | RESULT_SIZE(kFourByteCode)
        | STACK_ROUTINE_PARAMETER(1, kFourByteCode)
};
Here’s the code for the glue function.  Once you have the structure defined, create an instantiation of it, and initialize it.  Finally, call the component using CallUniversalProc as shown in the example.
pascal  ComponentResult  DrawerSetup (ComponentInstance myInstance, Rect *r)
{
#define kDrawerSetupParamSize     (sizeof (DrawerSetupParams))
#ifdef powerc
#pragma options align=mac68k
#endif
   struct DrawerSetupParams {
    Rect    *theRect;            /* Your parameters go here!!  In reverse                            order from parameter list. */
   };
   typedef struct DrawerSetupParams DrawerSetupParams;
   struct DrawerSetupGluePB {
    unsigned char        componentFlags;    /* Flags - set to zero */
    unsigned char        componentParamSize;    /* Size of the params struct */
    short            componentWhat;    /* The component request selector */
    DrawerSetupParams    params;        /* The parameters, see above */
    ComponentInstance    instance;        /* This component instance */
   };
   typedef struct DrawerSetupGluePB DrawerSetupGluePB;
#ifdef powerc
#pragma options align=reset
#endif
   DrawerSetupGluePB myDrawerSetupGluePB;
   myDrawerSetupGluePB.componentFlags = 0;
   myDrawerSetupGluePB.componentParamSize = kDrawerSetupParamSize;
   yDrawerSetupGluePB.componentWhat = kDrawerSetUpSelect;
   myDrawerSetupGluePB.params.theRect = r;
   myDrawerSetupGluePB.instance = myInstance;
   return CallUniversalProc(CallComponentUPP,
        uppCallComponentProcInfo,  &myDrawerSetupGluePB);
}
Repeat the above steps for all the public functions for your component.  To allow for future updating, the best way to make this glue available to your clients is to build the glue into a Code Fragment Manager shared library that is built into your component.  Provide your client with an XCOFF file to link against.  That way, if the glue changes, the client applications will not have to be relinked.  Be sure you choose a unique name for the glue library to avoid possible name conflicts.
Creating the extended thng' ComponentResource
Here is how to create the 'thng' ComponentResource for a component that supports both platform68k and platformPowerPC. This is the source for MPW Rez using the latest version of Types.r that supports the UseExtendedThingResource template. Before using the new Types.r you need to define the UseExtendedThingResource conditional with the value 1. A  component defined with this resource will work for all previous versions of the Component Manager. By keeping the original portions of the ComponentResource setup for the platform68k information, it allows your component to work on all 68K Macintosh computers. Adding the new information about your code fragment for the Power Macintosh allows the Component Manager for that machine to use your native code.
resource 'thng' (128, purgeable) {
    kComponentType,
    kComponentSubType,
    kComponentCreator,
    cmpWantsRegisterMessage,
    kAnyComponentFlagsMask,
    k68KCodeType, k68KCodeID,
    'STR ', kComponentNameStringID,
    'STR ', kComponentInfoStringID,
    'ICON', kComponentIconID,
#if UseExtendedThingResource
    0x00010001,                     /* version 1.1 */
    componentHasMultiplePlatforms,
    kComponentIconFamilyID,
    {
        cmpWantsRegisterMessage, k68KCodeType, k68KCodeID, platform68k,
        cmpWantsRegisterMessage, kPowerPCCodeType, kPowerPCCodeID, platformPowerPC
    };
#endif
};
If you have a component that only supports the 68K Macintosh, then you do not need to use the extended ComponentResource structure. However, if you wish to utilize Icon Families and automatic version registration, then use the extended ComponentResource without the ComponentPlatformInfo and do not set the componentHasMultiplePlatforms flag of the componentRegisterFlags. You may also include the ComponentPlatformInfo if you wish to and just have a single element that describes your 68K component code.
If you have a “fat” component, with both 68K and PowerPC code, set the component flags as you would for the 68K only case and duplicate that information in the ComponentPlatformInfo portion of the extended resource.  That will allow your component to work correctly for versions of the Component Manager that are not aware of the extended 'thng' resource.
If you have a component that only supports the PowerPC in native mode, then you must use the extended ComponentResource. In this case, some care must be taken so that the component will not be registered on 68K machines.  Set the ResourceSpec field in the non-extended part of the 'thng' resource to zero. In addition, set the component flags in the non-extended part  of the resource to cmpWantsRegisterMessage, regardless of whether or not you handle the register message.  This will cause the 68K Component Manager to attempt to register your component, it will fail, because there is no 68K code resource and your component will not be registered.
For the PowerPC case, you need to include a single ComponentPlatformInfo element that describes your PowerPC native component code for PowerPC implementations of your component to be registered.  Set the component flags in the extended portion of the resource as you would normally.
Component Manager interfaces
/* MPW Rez interfaces */
#define cmpWantsRegisterMessage         (1<<31)        /* bits for component
                                   flags */
#define componentDoAutoVersion         (1<<0)            /* bits for registration
                                      flags */
#define componentWantsUnregister        (1<<1)
#define componentAutoVersionIncludeFlags    (1<<2)
#define componentHasMultiplePlatforms    (1<<3)

type 'thng' {
    literal longint;                    /* Type */
    literal longint;                    /* Subtype */
    literal longint;                    /* Manufacturer */
    unsigned hex longint;                 /* component flags */
    unsigned hex longint    kAnyComponentFlagsMask = 0;    /* component flags Mask */
    literal longint;                    /* Code Type */
    integer;                        /* Code ID */
    literal longint;                    /* Name Type */
    integer;                        /* Name ID */
    literal longint;                    /* Info Type */
    integer;                        /* Info ID */
    literal longint;                    /* Icon Type */
    integer;                        /* Icon ID */
#if UseExtendedThingResource
    unsigned hex longint;                /* version of Component */
    longint;                        /* flags for registration */
    integer;                        /* resource id of Icon                                    Family */
    longint = $$CountOf(ComponentPlatformInfo);
    wide array ComponentPlatformInfo {
        unsigned hex longint;                 /* component  flags */
        literal longint;                    /* Code Type */
        integer;                        /* Code ID */
        integer platform68k = 1, platformPowerPC = 2;    /* platform type */
        };
#endif
};
/* MPW C interfaces */
enum {
#define gestaltComponentMgr     'cpnt'        /* Component Mgr version */
#define gestaltQuickTimeFeatures     'qtrs'        /* QuickTime features */
    gestaltPPCQuickTimeLibPresent = 0,        /* PowerPC QuickTime glue library                                is present */
#define gestaltSysArchitecture 'sysa'        /* Native System Architecture */
    gestalt68k = 1,                /* Motorola MC68K architecture */
    gestaltPowerPC = 2,                /* IBM PowerPC architecture */
    /* componentRegisterFlags flags for ComponentResourceExtension */
    componentDoAutoVersion         = (1<<0),
    componentWantsUnregister         = (1<<1),
    componentAutoVersionIncludeFlags     = (1<<2),
    componentHasMultiplePlatforms     = (1<<3)
};
struct ComponentPlatformInfo
{
    long            componentFlags;    /* flags of Component */
    ResourceSpec         component;        /* resource where Component code                                is found */
    short            platformType;        /* gestaltSysArchitecture
                               result */
};
typedef struct ComponentPlatformInfo ComponentPlatformInfo;
struct ExtComponentResource {
    ComponentDescription    cd;            /* Registration parameters */
    ResourceSpec     component;            /* resource where Component code                                is found */
    ResourceSpec    componentName;        /* name string resource */
    ResourceSpec    componentInfo;        /* info string resource */
    ResourceSpec    componentIcon;        /* icon resource */
    /* new data for Component Manager version 3 */
    long        componentVersion;        /* version of Component */
    long        componentRegisterFlags;    /* flags for registration */
    short        componentIconFamily;        /* resource id of Icon Family */
    long        count;                /* elements in platformArray */
    ComponentPlatformInfo platformArray[1];
};
typedef struct ExtComponentResource ExtComponentResource;
Further Reference:
•    Inside Macintosh: More Macintosh Toolbox (Component Manager)
•    Inside Macintosh: PowerPC System Software (Mixed Mode Manager and Code Fragment Manager)
•    Macintosh Technical Note, Drawing Icons the System 7 Way (M.IM.IconDrawing).
“◊#ˇˇˇˇˇ#◊†Ç

0ZÇ#
    0Ià:µú9"|    ˇˇˇˇˇˇˇˇ#†ƒ°d
ONLNf
˛†å°d1drw2
…-
·
_ġˇˇˇˇˇ

è°ñ
x°ddrw2:
°ddrw2:$°d4drw2:





°öˇ˙ó@†ò,Times

.
R
…R
…+]CNew Technical Notes†ô°ddrw2:°„
†ó°d1drw2
e
Ùġˇˇˇˇˇ

P°ñ
x°ddrw2:
°ddrw2:$°d4drw2:




°öˇ˚ÄE¿†ò
(|
ïDeveloper Support†ô°ddrw2:°„
†ó°d`drw2-
Ôˇˇˇˇˇˇ

K
Ô-
Z
 ggZ°d1drw2
 
¿
˙
Èˇˇˇˇˇˇ

K°ñ
x°ddrw2:
°ddrw2:$°d4drw2:
0



°öˇÙĆò
0(V
Ô
†ô°ddrw2:°„
†ó°d1drw2
Ô
Ê
˙
ˇˇˇˇˇˇ

°ñ
x°ddrw2:
°ddrw2:$°d4drw2:
    



°öˇ˝Ä†ò
    +&    
®†ô°ddrw2:°„
†ó°d1drw2
Â-
¯yˇˇˇˇˇˇ



°ñ
x°ddrw2:
°ddrw2:$°d4drw2:




°öˇ˚Ä%†ò
([\    Macintosh†ô°ddrw2:°„
†ó†ç°ddrw2D†É

IR
.



°dONLNdq<Ñ
ê(ûZ%QT 05 - Component Manager version 3.0
°dONLNd&É<èp*
    QuickTime°dONLNd0ÉÑè÷)H& Dave Radcliffe°dONLNdAÉ
ŏ
˛(´
„
March 1994°dONLNdLù<©T(≈ZThis 
°dONLNdQùT©
˛)Unote contains information regarding the version of the Component Manager that shipped°dONLNdß©<µ
›(—ZRwith QuickTime 1.6 and the changes necessary to support native PowerPC components.
°dONLNd˙√<œb*Topics°dONLNd

œW€
2+)• QuickTime 1.6 and Component Manager 3.0
°dONLNd
+€WÁ
*• Native PowerPC components

 
X

°dONLNd
G
<
!è(
=ZIntroduction
°dONLNd
T
/<
;
o*;The Component Manager in QuickTime 1.6.x and for the Power 
°dONLNd
è
/
o
;
˛(
W
çMacintosh (PowerPC) release°dONLNd
´
;<
G
(
cZ(has some new features. It has added the °dONLNd
”
;

G
˛)œ2ability to automatically resolve conflicts between°dONLNd
G<
S
(
oZ-different versions of the same component. It 
°dONLNd3
G

S
˛)‘2will ensure that only the most recent version of a°dONLNdf
S<
_
∂(
{ZKgiven component is actually registered. The Component Manager now supports 
°dONLNd±
S
∂
_
˛(
{
‘Icon Suites for°dONLNd¡
_<
k
/(
áZ1a component, so a component’s icon no longer has 
°dONLNdÚ
_
/
k
˛)Û,to be just black and white. In addition, the°dONLNd
k<
w
«(
ìZOComponent Manager can support code written in the native format of the PowerPC.
°dONLNdo
á<
ìõ*The result returned °dONLNdÉ
áõ
ì
)_for the Gestalt selector ,
Courier°dONLNdú
Ü

í
ï)ugestaltComponentMgr°dONLNdØ
á
ï
ì
˛)Ö will be 3, indicating°dONLNdΔ
ì<
ü
t(
ªZ?version number 3 of the Component Manager. This is the version 
°dONLNd
ì
t
ü
˛(
ª
íbeing discussed in this note.°dONLNd#
ü<
´
 (
«ZWTo insure that you have the features discussed here, check that version 3 is installed.°dONLNd{
∑<
√
:*2For support of the Power Macintosh, the Component 
°dONLNd≠
∑
:
√
˛)˛&Manager has been extended to allow use°dONLNd‘
√<
ϙ(
ÎZof native PowerPC 
°dONLNdÊ
√ô
œ
˛)]Bcomponents. When the Component Manager loads a native component on°dONLNd)
–<
‹»(
¯Zthe Power Macintosh, it calls 
°dONLNdG
–»
‹
ú)å)uses the Code Fragment Manager and calls °dONLNdp
œ
ú
€
˛)‘GetMemFragment°dONLNd
›<
Èá(Zand then later °dONLNdé
‹á
Ë)KCloseConnection°dONLNdù
›
È
Ö)i when it unloads your code °dONLNd∏
›
Ö
È
˛)ïresource (specified in a°dONLNd—
È<
ıœ(ZComponentPlatformInfo°dONLNdÊ
͜
ˆ⁄)ì). 
°dONLNdÈ
Í⁄
ˆ
˛)8This is how the Component Manager supports a native code°dONLNd"
ˆ<j(Z    fragment.
°dONLNd,<º*A component can support °dONLNdDº
˛)Ä<multiple platforms such as the 68K and PowerPC. Existing 68K°dONLNdÅ<&U(BZcode 
°dONLNdÜU&
˛)Sis always supported on the Power Macintosh through emulation. But you can also have°dONLNd⁄&<2
 (NZ*native PowerPC code for your component to °dONLNd&
 2
˛)‰)support better performance. The Component°dONLNd.2<>
n(ZZ@Manager will allow you to create a component that contains both 
°dONLNdn2
n>
˛(Z
åcode formats, so that you can°dONLNdå><J
(fZ/support all platforms with a single component. 
°dONLNdª>
J
˛)fl*The Component Manager also was extended in°dONLNdÊJ<V
‚(rZTa way that allows for native PowerPC only components (without any 68K code support). ’X’

*yQT 05 - Component Manager 3.0(Î
ˇ
1) of 12(
ZM.QT.Component Manager 3.0ˇ°¿
Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
†ø`◊#ˇˇˇˇˇ#◊

IR,Palatino

.+6-Macintosh Technical Notes 040
˘,Times

°dONLNd!‡*Extended ComponentResource
°dONLNd0<˝*+The ComponentResource data structure (the ',
Courier°dONLNdF/˝;
)Âthng°dONLNdJ0
<
U)' resource) °dONLNdV0
U<
⁄)<has been extended. These
°dONLNdo<H
å(d6Kextensions define additional information about the component. The complete °dONLNd∫<
åH
⁄(d
™data structure is°dONLNdÃIUt(q6shown below. The 
°dONLNd›ItU
4)\*first portion is the same as the existing °dONLNd
H
4T
´)¿ComponentResource°dONLNd
I
´U
⁄)w
, with the°dONLNd
#UaÓ(}6+new fields added at the end. The Component 
°dONLNd
NUÓa
⁄)÷0Manager determines if it is present by examining°dONLNd
bn`(ä6the size of the '°dONLNd
êa`m|)Hthng°dONLNd
îb|nØ)' resource.
    °dONLNd
†zÖ©(°6struct ExtComponentResource {°dONLNd
øÑ<è†+$
ComponentDescription°dONLNd
‘Ñ®è∑)lcd;°dONLNd
ڄ
è
•)l/* Registration parameters */°dONLNd
˘é<ô}(µZ
ResourceSpec °dONLNdéÑô∂)H
component;°dONLNdé
ô
π)ê!/* resource where Component code °dONLNd<ò
£
Z*
   is found */°dONLNdL¢<≠x(…ZResourceSpec°dONLNdY¢Ñ≠ )HcomponentName;°dONLNdi¢
≠
ñ)ê/* name string resource */°dONLNdÖ¨<∑x(”ZResourceSpec°dONLNdí¨Ñ∑ )HcomponentInfo;°dONLNd¢¨
∑
ñ)ê/* info string resource */°dONLNdæ∂<¡x(›ZResourceSpec°dONLNdÀ∂Ñ¡ )HcomponentIcon;°dONLNd€∂
¡
s)ê/* icon resource */°dONLNd <’
"(ÒZ./* new data for Component Manager version 3 */°dONLNd ‘<flP*
long°dONLNd&‘ÑflŸ)HcomponentVersion;°dONLNd9‘
fl
ñ)ê/* version of Component */°dONLNdUfi<ÈP(
Zlong°dONLNd[fiÑȘ)HcomponentRegisterFlags;°dONLNdsfi
È
†)ê/* flags for registration */°dONLNdëË<ÛU(
Zshort°dONLNdòËÑÛË)HcomponentIconFamily;°dONLNdÆË
Û
¥)ê /* resource id of Icon Family */°dONLNd–Ú<˝P(
Zlong°dONLNd÷ÚÑ˝¢)Hcount;°dONLNd‡Ú
˝
Ø)ê/* elements in platformArray */°dONLNd
¸<
ˇ(
#Z'ComponentPlatformInfo platformArray[1];°dONLNd)

"(
-6};

°dONLNd,

*Å*componentVersion°dONLNd>
7
C-*The °dONLNdB
6-
Bù)componentVersion°dONLNdR
7ù
C†)p
 
°dONLNdS
7†
C
⁄)?field contains the version number of the component. This should°dONLNdì
D
P¬(
l6&be identical to the value returned by °dONLNdπ
C¬
O
G)™GetComponentVersion°dONLNdÃ
D
G
P
¡)Ö. For convenience, if this 
°dONLNdÁ
D
¡
P
⁄)zvalue°dONLNdÌ
P
\î(
x6is set to 0, the component 
°dONLNd
Pî
\
⁄)|Dis called to get the version. This is useful during development. The°dONLNdM
]
i¢(
Ö6version number stored in the °dONLNdj
\¢
h
X)äComponentResourceExtension°dONLNdÑ
]
X
i
[)∂
 
°dONLNdÖ
]
[
i
⁄)is used by the Component°dONLNdû
i
u
,(
ë67Manager to avoid having to load and call the component °dONLNd’
i
,
u
⁄(
ë
J#to retrieve the component’s version°dONLNd˘
u
Å^(
ù6during startup.
°dONLNd    
è
õ£*componentRegisterFlags°dONLNd"
®
¥-*The °dONLNd&
ß-
≥«)componentRegisterFlags°dONLNd<
®«
¥
)ö) allow you to define additional register 
°dONLNde
®

¥
⁄)∏information. These°dONLNdx
¥
¿ï(
‹6flags are discussed below.
    °dONLNdî
Œ
Ÿ‡*(/* Component Resource Extension flags */°dONLNdΩ
‚
Ìã*componentDoAutoVersion °dONLNd◊
‚
Ì
)ÿ= (1<<0)°dONLNd‡
Ï
˜ê(6componentWantsUnregister°dONLNd˚
Ï
˜
)ÿ= (1<<1)°dONLNd
ˆ
∏(6 componentAutoVersionIncludeFlags°dONLNd&
ˆ

)ÿ= (1<<2)°dONLNd/©('6componentHasMultiplePlatforms°dONLNdN
)ÿ= (1<<3)
°dONLNdX%/(A6The °dONLNd\/$…)componentDoAutoVersion°dONLNdr…%
ß)ö+ flag tells the Component Manager that you °dONLNdù
ß%
⁄)fi    want your°dONLNdß%1Ä(M6component registered 
°dONLNdº%Ä1
⁄)hLonly if there is no later version available. If there is an older version of°dONLNd    1=õ(Y6the component installed, it °dONLNd%1õ=
⁄)É?will be unregistered. If an older version of the same component°dONLNde=I
–(e6aattempts to register after you, it will be immediately unregistered. Further, if a newer version 
°dONLNdΔ=
–I
⁄(e
Óof°dONLNd…IU
T(q6?the same component registers after you, you will automatically °dONLNd    I
TU
⁄(q
rbe unregistered. Using the°dONLNd    #Ua
ò(}6Nautomatic version control feature of the Component Manager allows you to make 
°dONLNd    qU
òa
⁄(}
∂sure that only°dONLNd    ÄamÌ(â6,the most recent version of your software is °dONLNd    ¨aÌm
⁄)’-running on a given machine, regardless of how°dONLNd    ⁄my∞(ï6many versions may be installed.°dONLNd    ˙Üí-*The 
°dONLNd    ˛Ö-ë’)componentWantsUnregister°dONLNd
Ü’í
⁄)®6 flag indicates that your component wants to be called°dONLNd
Míû
~(∫6Kwhen it is unregistered. This is useful if your component allocates global °dONLNd
òí
~û
⁄(∫
úmemory at register°dONLNd
´û™
=(Δ6>time, for example. The prototype of the unregister message is 
°dONLNd
Èû
=™
⁄(Δ
["identical to the register message. fi4fi
˘

(Û6
2) of 12(Û
qQT 05 - Component Manager 3.0+
M.QT.ComponentManager3.0ˇ ◊#ˇˇˇˇˇ#◊

IR,Palatino

.+Z-Developer Technical Support(-
˙
March 1994 0X0,Times
°dONLNd <,
(HZ-If your component has never been opened, its 
°dONLNd- 
,
˛)€0unregister message is not be called. The routine°dONLNd^,<8Ô(TZ'selector for unregister is given below.,
Courier
    °dONLNdÜF<Q√*kComponentUnregisterSelect °dONLNd£FQ
)¥= -7

°dONLNd©_<kR(áZThe °dONLNd≠^Rj
2) componentAutoVersionIncludeFlags°dONLNdÕ_
2k
c)‡ flag tells °dONLNdŸ_
ck
˛)1the Component Manager to use°dONLNdˆk<w
4(ìZ2the component flags as criteria for its component °dONLNd
(k
4w
˛)¯&search. If a component wants automatic°dONLNd
Ow<É

(üZ'version control, the Component Manager 
°dONLNd
vw

É
˛)≈3has to search for similar components. Normally, the°dONLNd
™Ñ<ê
Ä(¨Z<Component Manager searches only for another component using °dONLNd
ÊÑ
Äê
≤(¨
û
the type, °dONLNd
É
≤è
„)2subType°dONLNd
˜Ñ
„ê
˛)1, and
°dONLNd
˝ë<ù≥(πZmanufacturer fields of a °dONLNdê≥ú
?)wComponentDescription°dONLNd*ë
?ù
˛)å& record. This flag tells the Component°dONLNdQû<™™(ΔZManager to include the °dONLNdhù™©
)ncomponentFlags°dONLNdvû
™
K)b in its search.°dONLNdÜ∑<√S(flZThe °dONLNdä∂S¬
)componentHasMultiplePlatforms°dONLNdß∑
√
#)À
 °dONLNd®∑
#√
˛)+flag indicates that your component contains°dONLNd‘√<œê(ÎZmultiple versions 
°dONLNdÊ√êœ
˛)TJof the code for different platforms. If you plan on supporting the PowerPC°dONLNd1–<‹z(¯Znative code °dONLNd=–z‹
1)>!format, then you need to use the °dONLNd^œ
1€
ƒ)∑ComponentPlatformInfo°dONLNds–
ƒ‹
˛)ì within the°dONLNd›<È
(
Z0component resource structure. Then set this bit 
°dONLNdØ›
È
;)‡in the °dONLNd∂‹
;Ë
’)componentRegisterFlags°dONLNdÛ
’È
˛)ö
 field. If°dONLNd◊È<ı_(
Z    this bit 
°dONLNd‡È_ı
˛)#Vis not set then the code is assumed to be 68K format. Without this flag being set, the°dONLNd7ˆ<
Ï(
Z"Component Manager will ignore any °dONLNdYıÏ


)∞ComponentPlatformInfo°dONLNdnˆ


É)ì
.
°dONLNdp
<
π(
8ZcomponentIconFamily°dONLNdÖ
)<
5y*
Finally, the °dONLNdí
(y
4˛)=componentIconFamily°dONLNd•
)˛
5
˛)Ö1 field allows you to provide the resource ID of a°dONLNd◊
5<
A
ü(
]ZRSystem 7 Icon Suite. If this field is 0, it indicates that there is no icon suite.
°dONLNd*
O<
[[*count°dONLNd0
h<
t
*0This is the number of elements contained in the °dONLNd`
g

s
∞)·ComponentPlatformInfo°dONLNdu
h
∞
t
œ)ì array.
°dONLNd}
Ç<
éå(
™Z
platformArray
°dONLNdã
ö<
¶
*/This is an array of elements that describe the °dONLNd∫
ö

¶
˛)›/code to be used for different platforms. If the°dONLNdÍ
¶<
≤
J(
ŒZ1platform is for 68K, then the information within °dONLNd
¶
J
≤
˛(
Œ
hthis element is a copy from the°dONLNd;
≤<
æû(
€ZcomponentFlags°dONLNdI
≥û
øø)b of the °dONLNdQ
≤ø
æ
K)!ComponentDescription°dONLNde
≥
K
ø
b)å and 
°dONLNdj
≤
b
æ
∂)ResourceSpec°dONLNdv
≥
∂
ø
˛)T of the original°dONLNdá
ø<
˳(
ËZComponentResource°dONLNdò
¿≥
Ã
)w structure. This °dONLNd©
¿

Ã
˛)`*insures backwards compatibility with older
°dONLNd‘
Ã<
ÿ
Í(
ÙZSComponent Managers. If the component contains native code support for the PowerPC, °dONLNd'
Ã
Í
ÿ
˛(
Ùthen
°dONLNd,
Ÿ<
ÂØ(
Zan element of the array °dONLNdD
ŸØ
Â
k)s'will contain the information about its °dONLNdk
ÿ
k
‰
Õ)ºcomponentFlags°dONLNdy
Ÿ
Õ
Â
˛)b
, resource°dONLNdÑ
Â<
Ò¶(
Ztype, and resource ID.°dONLNdõ
˛<
Q*The °dONLNdü
˝Q    •)platformType°dONLNd´
˛•
Ô)T field is a value 
°dONLNdΩ
˛Ô

˛)J7that represents which platform the component code is to°dONLNdı<˚(3Z)support. The Gestalt result for selector °dONLNd
˚
ï)øgestaltSysArchitecture°dONLNd4
ï
È)ö will be matched °dONLNdE
È
˛)Twith
°dONLNdJ<$x(@Z
the value in °dONLNdWx#Ã)<platformType°dONLNdcÃ$)T of the °dONLNdk#
g)$ComponentResource°dONLNd|
g$
‘)w. If a match is found, °dONLNdì
‘$
˛)m    then that°dONLNdù$<0
(LZ+code is used to support the given platform.
    °dONLNd >`Ií+$
gestalt68k°dONLNd÷>ÃI‡)l= 1,°dONLNd›>
8I
›)l!/* Motorola MC68K architecture */°dONLNd    H`S¶(o~gestaltPowerPC°dONLNd    HÃS‡)l= 2,°dONLNd    H
8S
Œ)l/* IBM PowerPC architecture */°dONLNd    5`<k»(áZstruct ComponentPlatformInfo°dONLNd    Rj<uA*

{°dONLNd    Ut`t+$
long°dONLNd    \tÃ
)lcomponentFlags;°dONLNd    lt
8
∞)l/* flags of Component */°dONLNd    Ü~`âú(•~ResourceSpec°dONLNd    î~Ãâ˛)l
component;°dONLNd    †~
8â
›)l!/* resource where Component code °dONLNd    »à
8ì
~*
   is found */°dONLNd    ÿí`ùy(π~short°dONLNd    ‡íÃù

)l
platformType;°dONLNd    Ôí
8ù
Á)l#/* gestaltSysArchitecture result */°dONLNd
ú<ßF(√Z}; ’X’

*(QT 05 - Component Manager 3.0(Î
ˇ
3) of 12(
ZM.QT.Component Manager 3.0ˇL◊#ˇˇˇˇˇ#◊

IR,Palatino

.+6-Macintosh Technical Notes 040
˘,Times

°dONLNd /
*$Component Manager version 3 routines
°dONLNd%=I¢*GetComponentIconSuite,
Courier°dONLNd;Wc´*GetComponentIconSuite°dONLNdPX´d
5)ì returns an Icon Suite for the 
°dONLNdoX
5d
⁄)ä given component. This call works°dONLNdêdp1(å6only °dONLNdïd1p
⁄)Uunder System 7 or later. If called on System 6, it returns an error. If the component°dONLNdÎp|
É(ò6:doesn’t have an Icon Suite but does have a Component Icon °dONLNd
%p
É|
⁄(ò
°(as returned by
°dONLNd
5|àà(•6GetComponentInfo°dONLNd
E}àâî)p), °dONLNd
H|îà
')GetComponentIconSuite°dONLNd
]}
'â
ì)ì creates an Icon Suite °dONLNd
t}
ìâ
⁄)lcontaining just°dONLNd
Ñäñ
(≤65the black-and-white Component Icon. In this way, you 
°dONLNd
πä
ñ
G(≤
=can use °dONLNd
¡â
Gï
⁄)(GetComponentIconSuite°dONLNd
◊ñ¢Ù(æ6-whether or not a component has an Icon Suite.
    °dONLNd∞ª
è*Kpascal OSErr GetComponentIconSuite(Component aComponent, Handle *iconSuite)°dONLNdQƒœJ*
aComponent°dONLNd\ƒ`œ
K)H/Component ID, retrieved with FindNextComponent.°dONLNd匟E(ı6    iconSuite°dONLNdñŒ`Ÿ
7)H+Pointer to the Icon Suite you will receive.

°dONLNd¬ÊÚá(
6RegisterComponent°dONLNd‘Ú˛ª*RegisterComponentResource°dONLNdÓ˛

—*RegisterComponentResourceFile
°dONLNd

$
8*9The only change made to these routines was to modify the °dONLNdE

8
$
⁄(
@
V use of the global parameter. The
°dONLNdf
$
0
≈(
L6Vupper byte now contains the platform ID to be used by the component being registered. °dONLNdº
$
≈
0
⁄(
L
„This°dONLNd¡
1
=
c(
Y6Bchange is necessary because these calls do not have access to the °dONLNd
0
c
<
⁄(
Y
ÅComponentResource°dONLNd
>
Js(
f6which contains the °dONLNd(
=s
I
)[ComponentPlatformInfo°dONLNd=
>

J
G)ì. If the upper 
°dONLNdL
>
G
J
⁄)Abyte of the global parameter is°dONLNdl
K
WË(
s6-zero, then the platform is assumed to be the °dONLNdô
JË
V
5)–platform68k°dONLNd§
K
5
W
9)M
.

°dONLNd¶
q
Ä
M(
ú6)How to create a PowerPC ComponentResource
°dONLNd–
é
ö
ê*MThe basics step for running on a Power Macintosh with a native component are:°dONLNd
®
¥
>*:•  Create component code fragment with native PowerPC code°dONLNdY
¥
¿
;*>•  Main entry point to code is a mixed mode routine descriptor°dONLNdò
¿
Ã
*0•  Package component code fragment as a resource°dONLNd…
Ã
ÿ
‘*_•  If you supply an interface for the component to be called directly, then for PowerPC code to°dONLNd-
ÿ
‰
c*E   call your component you must provide custom glue to make the call.°dONLNds
Â
ÒÖ*
•  Create the extended '°dONLNdã
‰Ö
°)mthng°dONLNdè
°
Ò

)' resource using the °dONLNd§
‰



î)`ComponentPlatformInfo°dONLNd∫
ˇ
('67Each of these steps are discussed in more detail below:
°dONLNdÚ%Ú*$Creating the component code fragment
°dONLNd3?õ*The first step in creating a °dONLNd43õ?
⁄)É<native PowerPC component is to port your code.  For complete°dONLNdq?KÆ(g6details on porting to PowerPC, 
°dONLNdê?ÆK¡)ñsee °dONLNdî?¡K
¢)*Inside Macintosh: PowerPC System Software.°dONLNdæ?
¢K
⁄)·  Especially°dONLNdÀKWÁ(s6*important for the following discussion is °dONLNdıKÁW
⁄)œ+an understanding of the Mixed Mode and Code°dONLNd!Wcz(6Fragment Managers.°dONLNd4p|
*1Like other code ported for PowerPC, anytime your 
°dONLNdep
|
°)Ùcode uses a callback function (°dONLNdÑo
°{
“)ïProcPtr°dONLNdãp
“|
⁄)1),°dONLNdé}âé(•6it must be converted to a °dONLNd®|éà˛)vUniversalProcPtr°dONLNd∏}˛â
)p.  But 
°dONLNdø}
â
⁄)'unlike callbacks defined by the system,°dONLNdÁâï”(±6'callbacks to your component have their 
°dONLNd    â”ï
⁄)ª4own function prototypes.  With the exception of some°dONLNd    Cï°
}(Ω6Icallbacks defined for QuickTime components, there are no system supplied 
°dONLNd    åï
}°
⁄(Ω
õfunction prototypes°dONLNd    †¢Æ%( 6or °dONLNd    £°%≠ú)
UniversalProcPtrs°dONLNd    ¥¢úÆ
D)w$, so you must create these yourself. fi4fi
˘

(Û6
4) of 12(Û
qQT 05 - Component Manager 3.0+
M.QT.ComponentManager3.0ˇ|◊#ˇˇˇˇˇ#◊

IR,Palatino

.+Z-Developer Technical Support(-
˙
March 1994 0X0,Times
°dONLNd,<8[(TZIf, in °dONLNd,[8
˛)Qresponse to a request code, your component dispatches to internal functions using,
Courier
°dONLNdY8<Dœ(aZCallComponentFunction°dONLNdn9œE·)ì or °dONLNdr8·D
¡) CallComponentFunctionWithStorage°dONLNdí9
¡E
ˆ)‡, then this °dONLNdû9
ˆE
˛)5is°dONLNd°F<R…(nZa place where you must use a °dONLNdæE…Q
9)çUniversalProcPtr°dONLNdŒF
9R
=)p
.°dONLNd–^<j
†(ÜZHSuppose your component currently responds to an open request as follows:
    °dONLNd
x`É…+$switch (params->what)°dONLNd
1Ç`çe*

{°dONLNd
4å`óˆ*
    case kComponentOpenSelect:°dONLNd
Så
ó
n)¥/* Open request */°dONLNd
gñ`°y(Ω~    {°dONLNd
o†Ñ´
ÿ+$
Dresult = CallComponentFunctionWithStorage (storage, params, MyOpen);°dONLNd
∂™Ñµ¢*
break;°dONLNd
æ¥`øy(€~    }
°dONLNd
ƒÃ<ÿ
˘(ÙZ<MyOpen is an internal function callback, so you must create °dONLNdÃ
˘ÿ
˛(Ù
a°dONLNdÿ<‰
*(

Z"RoutineDescriptor/UniversalProcPtr°dONLNd$Ÿ
*Â
N)Ó
 for it.  °dONLNd.ÿ
N‰
x)$MyOpen°dONLNd4Ÿ
xÂ
‰)* is declared as follows:
    °dONLNdMÛ<˛
ü(
ZGpascal ComponentResult MyOpen (Handle storage, ComponentInstance self);
°dONLNdï
<
∫*The first step is to create a °dONLNd≥
∫
Ú)~ProcInfo°dONLNdª
Ú

`)8 value for this function:
    °dONLNd’
&<
1Z(
MZenum {°dONLNd‹
0<
;
*
(   uppMyOpenProcInfo = kPascalStackBased°dONLNd
:`
E
U+$
1| RESULT_SIZE(SIZE_CODE(sizeof(ComponentResult)))°dONLNd9
D`
O
s*
7| STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(Handle)))°dONLNdr
N`
Y
™*
B| STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(ComponentInstance)))°dONLNdµ
X<
cF(
Z};

°dONLNd∏
q<
}
*,Next you must update your source to build a °dONLNd‰
p

|
ä)fiUniversalProcPtr°dONLNdÙ
q
ä
}
∑)p     and use °dONLNd˝
q
∑
}
˛)-it.  You could°dONLNd
~<
äO(
¶Zuse 
°dONLNd
}O
â€)NewRoutineDescriptor°dONLNd$
~€
ä
˛)å> for this purpose, but the disadvantage is that creates a heap°dONLNdc
ä<
ñ
E(
≤Z5object which your component must dispose of properly.°dONLNdô
£<
Ø
*-An alternate approach is to declare a global °dONLNdΔ
¢

Æ
)ÃRoutineDescriptor°dONLNd◊
£

Ø
¶)w     (global 
°dONLNd‡
£
¶
Ø
˛)'variables are not a°dONLNdÙ
Ø<
ª
á(
◊Z>problem for a native PowerPC component, since a code fragment °dONLNd2
Ø
á
ª
˛(
◊
•automatically has global°dONLNdK
ª<
«m(
„Zvariables):
    °dONLNdW
’<
‡}*
#ifdef powerc°dONLNde
fl<
Í
÷*
RRoutineDescriptor MyOpenRD = BUILD_ROUTINE_DESCRIPTOR (uppMyOpenProcInfo, MyOpen);°dONLNd∏
È<
ÙZ*
#endif
°dONLNdø
<

ú*AIf you want your code to be compilable for both 68K and PowerPC, °dONLNd

ú

˛()
∫using the Universal°dONLNd
<
ˆ(5Z_Interfaces, then to avoid a lot of conditional compilation, the following macros may be useful:
    °dONLNdt'<2}*
#ifdef powerc°dONLNdÇ1<<
©*
I#define CallComponentFunctionWithStorageUniv(storage, params, funcName) \°dONLNdÃ;<F
ã*
C   CallComponentFunctionWithStorage(storage, params, &funcName##RD)°dONLNdE<P
E*
5#define CallComponentFunctionUniv(params, funcName) \°dONLNdFO<Z
'*
/   CallComponentFunction(params, &funcName##RD)°dONLNdvY<d
€*
S#define INSTANTIATE_ROUTINE_DESCRIPTOR(funcName) RoutineDescriptor funcName##RD = \°dONLNd c<n
w*
?   BUILD_ROUTINE_DESCRIPTOR (upp##funcName##ProcInfo, funcName)°dONLNd
m<xU*
#else°dONLNdw<Ç
©*
I#define CallComponentFunctionWithStorageUniv(storage, params, funcName) \°dONLNdZÅ<å
‡*
T   CallComponentFunctionWithStorage(storage, params, (ComponentFunctionUPP)funcName)°dONLNdØã<ñ
E*
5#define CallComponentFunctionUniv(params, funcName) \°dONLNdÂï<†
|*
@   CallComponentFunction(params, (ComponentFunctionUPP)funcName)°dONLNd    &ü<™Z*
#endif ’X’

*%QT 05 - Component Manager 3.0(Î
ˇ
5) of 12(
ZM.QT.Component Manager 3.0ˇt◊#ˇˇˇˇˇ#◊

IR,Palatino

.+6-Macintosh Technical Notes 040
˘,Times
°dONLNd!-Ñ*These macros, °dONLNd!Ñ-
 )lexactly analogous to ,
Courier°dONLNd# 
 ,
≥)úCallComponentFunction°dONLNd8!
≥-
⁄)ì and
°dONLNd=-9¯(V6 CallComponentFunctionWithStorage°dONLNd].¯:
ê)‡ , generate the appropriate code °dONLNd}.
ê:
⁄)ò
when compiled°dONLNdã:F…(b6 for 68K and PowerPC.  Note that °dONLNd´:…F
⁄)±1the PowerPC macro expansion depends on the global
°dONLNd›FRè(o6RoutineDescriptor°dONLNdÓGèSŒ)w name being °dONLNd˙FŒR
)?
FuncNameRD°dONLNd
G
S
)F, °dONLNd
G
S
⁄)%i.e. the name of the function with RD°dONLNd
,T`p(|6appended.  The °dONLNd
;Sp_
B)XINSTANTIATE_ROUTINE_DESCRIPTOR°dONLNd
YT
B`
≥)“ macro can be used °dONLNd
lT
≥`
⁄)qfor that°dONLNd
u`lA(à6purpose:
    °dONLNd
~zÖY*
#ifdef powerc°dONLNd
åÑè€*
'INSTANTIATE_ROUTINE_DESCRIPTOR(MyOpen);°dONLNd
¥éô6*
#endif
°dONLNd
ªß≥≈*(This is identical to the declaration of °dONLNd
„¶≈≤˝)≠MyOpenRD°dONLNd
Îß˝≥
ú)8% earlier, but simplifies the editing.°dONLNdøÀQ(Á6
With all the 
°dONLNdøQÀ
⁄)9Qconditional stuff out of the way, then the original code can simply be updated byN°dONLNdpÃÿî(Ù6
replacing °dONLNdzÀî◊
t)| CallComponentFunctionWithStorage°dONLNdöÃ
tÿ
≈)‡
 O°dONLNdõÃ
≈ÿ
⁄)Qwith°dONLNd†ÿ‰
(

6$CallComponentFunctionWithStorageUniv°dONLNdƒŸ
Â
)¸
:
    °dONLNd«Û<˛•(
Zswitch (params->what)°dONLNdfi˝<
A*

{°dONLNd·
<
Õ*
   case kComponentOpenSelect:°dONLNd



n)ÿ/* Open request */°dONLNd
<
P(
8Z   {°dONLNd
`
&
æ+$
Fresult = CallComponentFunctionWithStorageUniv(storage, params,MyOpen);°dONLNdd
%`
0~*
break;°dONLNdl
/<
:P(
VZ   }
°dONLNdq
G
S
h(
o6FRepeat the above steps for all internal component dispatches you make.
°dONLNd∏
a
m∂*Setting the main entry point
°dONLNd’
{
áŸ*(Lastly, you must set up the entry point °dONLNd˝
{Ÿ
á
⁄)¡1into your component correctly.  Unlike a 68K code°dONLNd/
á
ìΔ(
Ø6"resource, a PowerPC code fragment 
°dONLNdQ
áΔ
ì
⁄)Æ7(which your component will be) has a well defined entry°dONLNdâ
ì
ü
~(
ª6Lpoint.  The Component Manager, rather than just jumping to the start of the 
°dONLNd’
ì
~
ü
⁄(
ª
úcode resource, will°dONLNdÈ
ü
´
-(
«6<call the main entry point, as defined when linking, instead.°dONLNd&
∑
√
ß*IBut the Component Manager is 68K code, which means your main entry point °dONLNdo
∑
ß
√
⁄(
fl
≈    must be a°dONLNdy
√
Ϗ(
Ï6RoutineDescriptor°dONLNdä
ď
–
*)w".  You can set that up as follows:
    °dONLNd≠
fi
È6(6pascal°dONLNd¥
fi<
Èá)$ComponentResult°dONLNdƒ
fi®
Ⱥ)lmain°dONLNd…
fiÃ
È
0)$(ComponentParameters°dONLNdfi
fi
8
È
`)l*params,°dONLNdÏ
ËÃ
ÛÔ(Í Handle°dONLNdÙ
Ë

Û
_)H      storage);°dONLNd
Ú
˝Y(6
#ifdef powerc°dONLNd
¸6*
enum {°dONLNd<Î+$
#uppMainProcInfo = kPascalStackBased°dONLNdA`
U+$
1| RESULT_SIZE(SIZE_CODE(sizeof(ComponentResult)))°dONLNdv`%
æ*
F| STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ComponentParameters *)))°dONLNd¿$`/
s*
7| STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Handle)))°dONLNd¯.9"(U6};°dONLNd˚BM
è*KRoutineDescriptor MainRD = BUILD_ROUTINE_DESCRIPTOR(uppMainProcInfo, main);°dONLNdGLW6*
#endif
°dONLNdNeq
*3When you link the component, you must then specify °dONLNdÅd
p
B(ç
6MainRD°dONLNdáe
Bq
ö)* as the entry point.
°dONLNdúã7(ß6Note:
°dONLNd¢<ã
Ç)$>Your development environment may issue a warning because your °dONLNd‡
Çã
∂(ß
†
main entry°dONLNdÎã<ó
ù(≥ZLpoint is in a data section, not a code section.  You may ignore the warning. fi4fi
˘

(Û6
6) of 12(Û
qQT 05 - Component Manager 3.0+
M.QT.ComponentManager3.0ˇö◊#ˇˇˇˇˇ#◊

IR,Palatino

.+Z-Developer Technical Support(-
˙
March 1994 0X0,Times

°dONLNd <,[(HZNote:°dONLNd `,k)$If 
°dONLNd     k,
⁄)Jyour code is dependent on C or C++ runtime initializations, then your main°dONLNdT-`9Õ(U~entry point would be ,
Courier°dONLNdi,Õ8
)m__start °dONLNdq,
8
s):or __cplusstart°dONLNdÄ-
s9
⁄)l, respectively, rather°dONLNdó9`E
`(a~4than main.  Modify the previous example accordingly.
°dONLNdÃS<_[({ZNote:°dONLNd—S[_
¶)D Some components rely on a “fast dispatching” mechanism for calling 
°dONLNd
S
¶_
⁄({
ƒ    component°dONLNd
_`k∑(á~functions.  This °dONLNd
0_∑k
⁄)W5mechanism is dependent on the 68K architecture and is°dONLNd
fk`w∑(ì~unsupported for °dONLNd
vk∑w
⁄)W5native components, although it will work for emulated°dONLNd
¨w`É
;(ü~*components running on the Power Macintosh.
°dONLNd
◊ë<ù[(πZNote:°dONLNd
‹ë[ù
Ã)R In all these modifications for PowerPC, the most difficult thing to get right is 
°dONLNd.ë
Ãù
⁄(π
Íthe°dONLNd2ù`©ò(Δ~ProcInfo°dONLNd:ûò™
1)8" value.  It’s very easy to make a 
°dONLNd\û
1™
⁄)ô$“cut and paste” error, or get a type°dONLNdÅ™`∂Ì(“~wrong (short instead of short 
°dONLNdü™Ì∂
⁄)ç2*).  If your component is crashing the first thing°dONLNd“∑`√
N(fl~2to check (and check and check and check!) are the °dONLNd∂
N¬
Ü)ÓProcInfo°dONLNd∑
Ü√
´)8 values.
°dONLNd—<›
](˘Z/Packaging the PowerPC component into a resource°dONLNdEÎ<˜
.*.PowerPC development tools create your PowerPC 
°dONLNdsÎ
.˜
˛)Ú+code in a code fragment in the data fork of°dONLNdü˜<

£(
ZLthe file.  Your component code must be a resource (the resource type and id 
°dONLNdΘ
£

˛(

¡are specified in the°dONLNd
<
@(
,Z
'°dONLNd

@
\)thng°dONLNd
\

&)*' resource described below).  You can use 
°dONLNd/

&

˛) 'the MPW Rez “read” command to read from°dONLNdW
<

(
8Z,the data fork into a resource.  For example:
    °dONLNdÖ
*`
5

+$"read 'mycp' (130) mycomponent.pef;
°dONLNd®
C<
O\(
kZreads °dONLNdÆ
C\
O
)  the code fragment from the file °dONLNdŒ
B

N
w)≤mycomponent.pef°dONLNd›
C
w
O
˛)i and creates the resource°dONLNd˜
P<
\@(
xZ
'°dONLNd¯
O@
[\)mycp°dONLNd¸
P\
\~)'(130).
°dONLNd
j<
v
(
íZ'Providing an interface to the component°dONLNd,
Ñ<
ê‡*!If you wish your component to be 
°dONLNdM
ч
ê
˛)§=called directly, you must also supply an interface so callers°dONLNdã
ê<
ú
(
∏Z.know how to call it.  For standard functions, 
°dONLNdπ
ê

ú
˛)◊1such as Open, Close, Version, etc., this is not a°dONLNdÎ
ú<
®
ô(
ƒZCproblem as the Component Manager supplies functions to do this for °dONLNd.
ú
ô
®
˛(
ƒ
∑you.  Nor is this a°dONLNdB
®<
¥ª(
–Zproblem if you are writing 
°dONLNd]
®ª
¥
˛)?QuickTime components, as QuickTime supplies standard interfaces°dONLNdù
¥<
¿È(
‹Z%and libraries for calling components.°dONLNd√
Ã<
ÿd*But one 
°dONLNdÀ
Ãd
ÿ
˛)(Rof the advantages of the Component Manager is it lets you define your own routines°dONLNd
ÿ<
‰
g(Z@with their own parameter lists, and for these routines you must 
°dONLNd^
ÿ
g
‰
˛(
Ö supply an interface.  Typically,°dONLNd
‰<

0(Z5for 68K this involved providing callers an interface 
°dONLNd¥
‰
0

˛)Ù,file with function prototypes for your calls°dONLNd·
<
¸
((Z2and inline 68K assembly to actually make the call.°dONLNd<
y*AObviously, the inline 68K code is a problem for a native PowerPC 
°dONLNdU
y
˛(0
ócaller, so you must provide°dONLNdq< »(<Zglue to accomplish the same °dONLNdç» 
˛)å>thing.  The following discussion also applies to calling a 68K°dONLNdà <,
é(HZDcomponent from PowerPC code.  The interface is the same, either way.
°dONLNd    8<D≥*To take the example for °dONLNd    )8≥D‘)wInside °dONLNd    08‘D
â)!!Macintosh: More Macintosh Toolbox°dONLNd    Q8
âD
˛)µ, page 6-30, you might°dONLNd    hD<PÑ(lZhave a call like:
    °dONLNd    z^<i
∏*Lpascal ComponentResult DrawerSetup (ComponentInstance myInstance, Rect *r) =°dONLNd    «h<s
*
-    ComponentCallNow (kDrawerSetUpSelect, 4);
°dONLNd    ıÄ<å¨*ComponentCallNow°dONLNd
Ũç
,)p is a macro that expands °dONLNd
Å
,ç
˛)Ä)to inline 68K code that pushes additional°dONLNd
Hç<ô
é(µZEparameters and then executes an A-trap to call the Component Manager. ’X’

*6QT 05 - Component Manager 3.0(Î
ˇ
7) of 12(
ZM.QT.Component Manager 3.0ˇfi◊#ˇˇˇˇˇ#◊

IR,Palatino

.+6-Macintosh Technical Notes 040
˘,Times
°dONLNd
f*
9The first thing when using the new Universal Headers, is °dONLNd9
f
⁄(:
Ñthat the definition of,
Courier°dONLNdP*à(G6ComponentCallNow°dONLNd`à+
∞)p> has changed slightly.  The above declaration would change to:
    °dONLNdü9D
ä(`6Jpascal ComponentResult DrawerSetup (ComponentInstance myInstance, Rect *r)°dONLNdÎCN˘*
-    ComponentCallNow (kDrawerSetUpSelect, 4);
°dONLNd
[g
*8The only difference in this declaration is that the ‘=’ 
°dONLNd
Q[
g
⁄)˜+character is missing.  This is necessary to°dONLNd
}gs
(è63allow the code to compile for both 68K and PowerPC.°dONLNd
±Äåj*For 68K code, °dONLNd
øjã⁄)RComponentCallNow°dONLNd
πڌ
y)p continues to expand to inline °dONLNd
ÓÄ
yå
⁄)ü68K code, but for°dONLNdçôb(µ6
PowerPC, the °dONLNd
åbò“)JComponentCallNow°dONLNdç“ô˘)p macro °dONLNd$ç˘ô
⁄)')expands to nothing, which means the above°dONLNdNô•Å(¡6declaration reduces to:
    °dONLNdf≥æ
î*Lpascal ComponentResult DrawerSetup (ComponentInstance myInstance, Rect *r) ;

°dONLNd≥Ãÿ≤*You must now supply glue for °dONLNd–À≤◊ˇ)öDrawerSetup°dONLNd€Ãˇÿ
Ã)M( that does the same thing on PowerPC as °dONLNdÃ
Ãÿ
⁄)Õthe°dONLNdÿ‰É(
668K inlines would do.°dONLNd¸
√*VThe strategy here is to mimic what 68K code calling your component would do.  Namely, 
°dONLNdu
√¸
⁄(

·push°dONLNdz¸
Ÿ(
$6)a bunch of parameters on the stack, then 
°dONLNd£¸Ÿ

⁄)¡5call the component.  You do that by building a struct°dONLNdŸ

©(
06that looks like the parameters 
°dONLNd¯
©

å)ë%as they would appear on the 68K stack°dONLNd

å

≥)„.  Each °dONLNd%

≥

⁄)'    call will°dONLNd/

 
m(
<6Krequire a different struct because each call can have different parameters.°dONLNd{
-
9ê*Use the struct below (°dONLNdë
,ê
8
)xDrawerSetupGluePB°dONLNd¢
-

9
h)w) as a template.  °dONLNd¥
-
h
9
⁄)aThe first three fields,°dONLNdÃ
9
Ez(
b6componentFlags°dONLNd⁄
:z
FÉ)b, °dONLNd‹
9É
E

)    componentParamSize°dONLNdÓ
:


F
 )~, and °dONLNdÙ
9
 
E
{)
componentWhat°dONLNd

:
{
F
“)[ are required, as °dONLNd
:
“
F
⁄)Wis°dONLNd
F
Rı(
n60the last field, which is the component instance.°dONLNdG
^
jz*componentFlags°dONLNdU
_z
k

)b is unused and should be zero.°dONLNdt
w
Éñ(
†6componentParamSize°dONLNdÜ
xñ
ѧ)~ is 
°dONLNdä
x§
Ñ
⁄)Cthe size, in bytes, of the parameters to the call, not counting the°dONLNdŒ
Ñ
êP(
¨6
component °dONLNdÿ
ÑP
ê
⁄)8Ninstance.  This is the same number that is passed as the second parameter in a
°dONLNd'
ê
úà(
π6ComponentCallNow°dONLNd7
ëà
ù
I)p' macro call, and should be the same as °dONLNd^
ë
I
ù
⁄)¡the size of the params struct,°dONLNd}
ù
©j(
≈6discussed below.°dONLNdé
µ
¡s*
componentWhat°dONLNdõ
∂s
¬„)[ is the selector for your 
°dONLNdµ
∂„
¬
⁄)p4component call.  Its the same as the first parameter°dONLNdÍ
√
œ,(
Î6to a °dONLNdÔ
¬,
Œú)ComponentCallNow°dONLNdˇ
√ú
œ”)p macro call.°dONLNd
€
Á
ë(6MThe params field is a separate struct that exactly mirrors your parameters.  °dONLNdY
€
ë
Á
⁄(
Ø
 This must be°dONLNdg
Á
Ûe(6customized for °dONLNdv
Áe
Û
⁄)MKyour call.  A separate struct is used here because it simplifies the sizeof
°dONLNd¬
Ùr(6calculation for the °dONLNd÷
Ûr
ˇ)ZcomponentParamSize°dONLNdË
Ù
Z)~ field.  Parameters in °dONLNdˇ
Ù
Z
⁄)jthis struct are specified in°dONLNd:((6reverse°dONLNd#:«)" order from the parameter list.
°dONLNdE&7(B6Note:°dONLNdK<&é)$Remember that °dONLNdYé&
h)R(the struct mirrors 68K stack alignment, °dONLNdÅ
h&
w)⁄not°dONLNdÑ
w&
∂) 68K struct°dONLNdê&<2q(NZalignment. 
°dONLNdõ&q2
∂)5B This means that byte parameters, e.g. char or Boolean, get passed°dONLNdfi2<>
¢(ZZMas two bytes, not one. The struct must mirror that fact, so you must declare 
°dONLNd    +2
¢>
∂(Z
¿byte°dONLNd    0><J{(fZfields to be a 
°dONLNd    ?>{J
∂)?Cbyte field followed by a pad byte field and take it into account in°dONLNd    ÉJ<V÷(rZ!your parameter size calculations.
°dONLNd    ßdpv(å6Once you have the °dONLNd    πdvp
⁄)^Istruct, initialize it as shown in the example, and call the component via°dONLNd
p|è(ô6CallUniversalProc°dONLNd
qè}ª)w
 with the °dONLNd
pª|
+),CallComponentUPP°dONLNd
.q
+}
5)p.  °dONLNd
1p
5|
•)
CallComponentUPP°dONLNd
Aq
•}
≥)p is 
°dONLNd
Eq
≥}
⁄)declared°dONLNd
N~äê(¶6for you and is part of the °dONLNd
i}êâ‰)xInterfaceLib°dONLNd
u~‰ä
Õ)T3.  You don't need to do anything special to use it.°dONLNd
©ñ¢¿(ø6uppCallComponentProcInfo°dONLNd
¡ó¿£≈)®
 °dONLNd
¬ó≈£
⁄)7should have been in the interfaces, because the call is°dONLNd
˙£Ø

(À65always the same, but it's not, so it's defined below. fi4fi
˘

*(
8) of 12(Û
qQT 05 - Component Manager 3.0+
M.QT.ComponentManager3.0ˇæ◊#ˇˇˇˇˇ#◊

IR,Palatino

.+Z-Developer Technical Support(-
˙
March 1994 0X0,
Courier
    °dONLNd<<GZ(cZenum {°dONLNdF<Q
,*
0    uppCallComponentProcInfo = kPascalStackBased°dONLNd:PÑ[
+H
| RESULT_SIZE(kFourByteCode)°dONLNdYZÑe
[*
+| STACK_ROUTINE_PARAMETER(1, kFourByteCode)°dONLNdÖd<oF(ãZ};,Times
°dONLNdàÜ<í
A*#1Here’s the code for the glue function.  Once you °dONLNdπÜ
Aí
˛(Æ
_%have the structure defined, create an°dONLNdflì<ü–(ªZ$instantiation of it, and initialize 
°dONLNd
ì–ü
á)î'it.  Finally, call the component using °dONLNd
*í
áû
˛)∑CallUniversalProc°dONLNd
<ü<´¥(«Zas shown in the example.
    °dONLNd
Uµ<¿
∏*Lpascal  ComponentResult  DrawerSetup (ComponentInstance myInstance, Rect *r)°dONLNd
£ø< A*

{°dONLNd
•…<‘Õ*
#define kDrawerSetupParamSize°dONLNd
√…‘
Å)¥ (sizeof (DrawerSetupParams))°dONLNd
·›<Ë}(
Z
#ifdef powerc°dONLNd
ÔÁ<Ú»*
#pragma options align=mac68k°dONLNdÒ<¸Z*
#endif°dONLNd˚<
Õ*
   struct DrawerSetupParams {°dONLNd2
`
t+$
Rect°dONLNd7
Ñ
±)$    *theRect;°dONLNdC



‹)ê(/* Your parameters go here!!  In reverse°dONLNdr



¥*
    order from parameter list. */°dONLNdì
<
$U(
@Z   };°dONLNdô
#<
.
J*
6   typedef struct DrawerSetupParams DrawerSetupParams;°dONLNd–
7<
BÕ*   struct DrawerSetupGluePB {°dONLNdÔ
A`
L°+$

unsigned char°dONLNd˛
AÃ
L
)lcomponentFlags;°dONLNd
A
8
L
µ)l/* Flags - set to zero */°dONLNd)
K`
V°(
r~
unsigned char°dONLNd8
KÃ
V
+)lcomponentParamSize;°dONLNdL
K
8
V
”)l/* Size of the params struct */°dONLNdm
U`
`y(
|~short°dONLNdu
UÃ
`
)lcomponentWhat;°dONLNdÑ
U
8
`
Ï)l$/* The component request selector */°dONLNd™
_`
jµ(
Ü~DrawerSetupParams°dONLNdº
_Ã
jÔ)lparams;°dONLNd≈
_
8
j
”)l/* The parameters, see above */°dONLNdÊ
i`
tµ(
ê~ComponentInstance°dONLNd¯
iÃ
t˘)l    instance;°dONLNd
i
8
t
…)l/* This component instance */°dONLNd!
s<
~U(
öZ   };°dONLNd'
}<
à
J*
6   typedef struct DrawerSetupGluePB DrawerSetupGluePB;°dONLNd^
á<
í}*

#ifdef powerc°dONLNdl
ë<
ú√*
#pragma options align=reset°dONLNdà
õ<
¶Z*
#endif°dONLNdè
•<
∞
    *
)   DrawerSetupGluePB myDrawerSetupGluePB;°dONLNdπ
π<
ƒ
**   myDrawerSetupGluePB.componentFlags = 0;°dONLNd‰
√<
Œ
Ü*
B   myDrawerSetupGluePB.componentParamSize = kDrawerSetupParamSize;°dONLNd'
Õ<
ÿ
Y*
9   yDrawerSetupGluePB.componentWhat = kDrawerSetUpSelect;°dONLNda
◊<
‚
*
*   myDrawerSetupGluePB.params.theRect = r;°dONLNdå
·<
Ï
*
-   myDrawerSetupGluePB.instance = myInstance;°dONLNd∫
ı<
*-   return CallUniversalProc(CallComponentUPP,°dONLNdÍ
ˇÑ

y+H
1uppCallComponentProcInfo,  &myDrawerSetupGluePB);°dONLNd    <A(0Z
}

°dONLNd!<-
û*IRepeat the above steps for all the public functions for your component.  °dONLNdg!
û-
˛(I
ºTo allow for future
°dONLNd{-<9
2(UZ3updating, the best way to make this glue available °dONLNdÆ-
29
˛)ˆ+to your clients is to build the glue into a°dONLNd⁄9<E¯(aZ%Code Fragment Manager shared library 
°dONLNdˇ9¯E
˛)º7that is built into your component.  Provide your client°dONLNd7E<Q
(mZ*with an XCOFF file to link against.  That 
°dONLNdaE
Q
˛)Δ6way, if the glue changes, the client applications will°dONLNdòQ<]
’(yZPnot have to be relinked.  Be sure you choose a unique name for the glue library °dONLNdËQ
’]
˛(y
Ûto avoid°dONLNdÒ]<iÆ(ÖZpossible name conflicts.
°dONLNd
w<É
Q*-Creating the extended thng' ComponentResource ’X’

*LQT 05 - Component Manager 3.0(Î
ˇ
9) of 12(
ZM.QT.Component Manager 3.0ˇt◊#ˇˇˇˇˇ#◊

IR,Palatino

.+6-Macintosh Technical Notes 040
˘,Times
°dONLNdî*Here is how to create the ',
Courier°dONLNdî∞)|thng°dONLNd∞∑)' °dONLNd!∑
.)ComponentResource°dONLNd2
.
B)w for 
°dONLNd7
B
⁄)a component that supports both°dONLNdV+e(H6platform68k°dONLNda e,~)M and °dONLNdf~+Á)platformPowerPC°dONLNdu Á,
Ø)i'. This is the source for MPW Rez using °dONLNdú 
Ø,
⁄)»
the latest°dONLNdß-9ƒ(U6%version of Types.r that supports the °dONLNdÃ,ƒ8
l)¨UseExtendedThingResource°dONLNd‰-
l9
¿)® template. Before 
°dONLNdˆ-
¿9
⁄)Tusing°dONLNd¸:FÅ(b6the new Types.r you °dONLNd
:ÅFfl)ineed to define the °dONLNd
#9flE
á)^UseExtendedThingResource°dONLNd
;:
áF
⁄)® conditional with°dONLNd
MFR
V(n6Cthe value 1. A  component defined with this resource will work for 
°dONLNd
êF
VR
⁄(n
tall previous versions of the°dONLNd
≠S_
2({67Component Manager. By keeping the original portions of °dONLNd
‰S
2_
E({
Pthe °dONLNd
ËR
E^
º)ComponentResource°dONLNd
˘S
º_
⁄)w setup°dONLNd`l:(à6for the °dONLNd_:ká)"platform68k°dONLNd`ál»)M information, 
°dONLNd!`»l
⁄)A5it allows your component to work on all 68K Macintosh°dONLNdWlx
(î61computers. Adding the new information about your °dONLNdàl
x
⁄)˝%code fragment for the Power Macintosh°dONLNdÆxÑ
q(†6Fallows the Component Manager for that machine to use your native code.
    °dONLNdıíù¬*"resource 'thng' (128, purgeable) {°dONLNdúßw*
    kComponentType,°dONLNd,¶±Ü*
    kComponentSubType,°dONLNdC∞ªÜ*
    kComponentCreator,°dONLNdZ∫≈§*
    cmpWantsRegisterMessage,°dONLNdwƒœü*
    kAnyComponentFlagsMask,°dONLNd쌟©*
    k68KCodeType, k68KCodeID,°dONLNd±ÿ„«*
#    'STR ', kComponentNameStringID,°dONLNd’‚Ì«*
#    'STR ', kComponentInfoStringID,°dONLNd˘Ï˜©*
    'ICON', kComponentIconID,°dONLNd

§*#if UseExtendedThingResource°dONLNd4



!*
5    0x00010001,                     /* version 1.1 */°dONLNdj

¬*
"    componentHasMultiplePlatforms,°dONLNdç

)ü*
    kComponentIconFamilyID,°dONLNd©
(
31*
    {°dONLNdØ
2
=
{*
G        cmpWantsRegisterMessage, k68KCodeType, k68KCodeID, platform68k,°dONLNd˜
<
G
≤*
R        cmpWantsRegisterMessage, kPowerPCCodeType, kPowerPCCodeID, platformPowerPC°dONLNdJ
F
Q6*
    };°dONLNdQ
P
[6*
#endif°dONLNdX
Z
e"*
};
°dONLNd[
r
~8*If you 
°dONLNdb
r8
~
⁄) Rhave a component that only supports the 68K Macintosh, then you do not need to use°dONLNdµ

ãV(
ß6
the extended °dONLNd¬
~V
äÕ)>ComponentResource°dONLNd”
Õ
ã
l)w! structure. However, if you wish 
°dONLNdÙ

l
ã
⁄)üto utilize Icon Families°dONLNd

å
ò’(
¥6)and automatic version registration, then 
°dONLNd6
å’
ò
))Ωuse the extended °dONLNdG
ã
)
ó
†)TComponentResource°dONLNdX
å
†
ò
⁄)w without the°dONLNde
ò
§´(
¡6ComponentPlatformInfo°dONLNdz
ô´
•Ø)ì
 °dONLNd{
ôØ
•
)and do not set the °dONLNdé
ò

§
⁄)`componentHasMultiplePlatforms°dONLNd¨
¶
≤;(
Œ6flag °dONLNd±
¶;
≤w)#of the °dONLNd∏
•w
±
)<componentRegisterFlags°dONLNdŒ
¶

≤
⁄)ö. You may also include the°dONLNdÈ
≤
æ´(
€6ComponentPlatformInfo°dONLNd˛
≥´
ø
Æ)ì4 if you wish to and just have a single element that °dONLNd2
≥
Æ
ø
⁄(
€
à    describes°dONLNd<
ø
Àö(
Á6your 68K component code.°dONLNdU
◊
„ı*-If you have a “fat” component, with both 68K 
°dONLNdÇ
◊ı
„
⁄)›,and PowerPC code, set the component flags as
°dONLNdØ
„
Ô
p(63you would for the 68K only case and duplicate that °dONLNd‚
„
p
Ô
⁄(
éinformation in the°dONLNdı
Ô
˚´(6ComponentPlatformInfo°dONLNd

´
¸
à)ì) portion of the extended resource.  That °dONLNd3

à
¸
⁄)›will allow your°dONLNdC
¸
7($6:component to work correctly for versions of the Component 
°dONLNd}
¸
7
⁄($
U!Manager that are not aware of the°dONLNdü    I(16
extended '°dONLNd©Ie)1thng°dONLNd≠    eò)' resource.°dONLNdπ!-8(I6If you 
°dONLNd¿!8-
⁄) Qhave a component that only supports the PowerPC in native mode, then you must use°dONLNd    .:Z(V6
the extended °dONLNd    -Z9—)BComponentResource°dONLNd    0.—:⁄)w. °dONLNd    2.⁄:
⁄)    1In this case, some care must be taken so that the°dONLNd    d;G
5(c6;component will not be registered on 68K machines.  Set the °dONLNd    ü:
5F
â(c
SResourceSpec°dONLNd    ´;
âG
å)T
 
°dONLNd    ¨;
åG
÷)field in the non°dONLNd    º;
÷G
⁄)J
-°dONLNd    ΩHT|(p6extended part of the '°dONLNd    ”G|Sò)dthng°dONLNd    ◊HòT )' resource 
°dONLNd    ‚H T
÷)28to zero. In addition, set the component flags in the non°dONLNd
H
÷T
⁄(p
Ù
-
°dONLNd
Uaπ(}6"extended part  of the resource to °dONLNd
=Tπ`
Z)°cmpWantsRegisterMessage°dONLNd
TU
Za
b)°, °dONLNd
VU
ba
ñ)regardless °dONLNd
aU
ña
⁄)4
of whether or°dONLNd
oamƒ(â6$not you handle the register message.°dONLNd
ìaƒm«)¨
 
°dONLNd
îa«m
⁄)5 This will cause the 68K Component Manager to attempt°dONLNd
 my‡(ï6*to register your component, it will fail, °dONLNd
Ùm‡y
⁄)».because there is no 68K code resource and your°dONLNd#yÖ∂(°6!component will not be registered.
°dONLNdEíû£*For the PowerPC case, you °dONLNd_í£û
)ãneed to include a single °dONLNdxë
ù
±){ComponentPlatformInfo°dONLNdçí
±û
⁄)ì element
°dONLNdñû™…(Δ6#that describes your PowerPC native °dONLNdπû…™
⁄)±2component code for PowerPC implementations of your fi4fi
˘

(Û610)
 of 12(Û
qQT 05 - Component Manager 3.0+
M.QT.ComponentManager3.0ˇN◊#ˇˇˇˇˇ#◊

IR,Palatino

.+Z-Developer Technical Support(-
˙
March 1994 0X0,Times
°dONLNd <,
®(HZMcomponent to be registered.  Set the component flags in the extended portion 
°dONLNdM 
®,
˛(H
Δof the resource as°dONLNd`,<8†(TZyou would normally.

°dONLNduR<a

*)Component Manager interfaces,
Courier
    °dONLNdío<z¥*/* MPW Rez interfaces */°dONLNd´É<é‹* #define cmpWantsRegisterMessage °dONLNdÕÉ
é
K)ÿ(1<<31)    °dONLNdŸÉ
\é
≈)H/* bits for component°dONLNd¯ç
\ò
ì*
   flags */°dONLNd
°<¨◊(»Z#define componentDoAutoVersion °dONLNd
%°
¨
2)ÿ(1<<0)°dONLNd
,°
8¨
L)$    °dONLNd
1°
\¨
‘)$/* bits for registration°dONLNd
Q´
8∂
í(“
V          flags */°dONLNd
dµ<¿‹(‹Z #define componentWantsUnregister°dONLNd
ܵ
¿
2)ÿ(1<<1)°dONLNd
çø< 
(ÊZ(#define componentAutoVersionIncludeFlags°dONLNd
∂ø
 
2)ÿ(1<<2)°dONLNd
Ω…<‘ı(Z%#define componentHasMultiplePlatforms°dONLNd
„…
‘
2)ÿ(1<<3)°dONLNd
Ò›<Ë}(
Z
type 'thng' {°dONLNdÁ`Ú∞+$
literal longint;°dONLNdÁ
\Ú
é)¸
/* Type */°dONLNd!Ò`¸∞(
~literal longint;°dONLNd6Ò
\¸
ù)¸
/* Subtype */°dONLNdE˚`
∞(
"~literal longint;°dONLNdZ˚
\

∂)¸/* Manufacturer */°dONLNdn
`
Œ(
,~unsigned hex longint; °dONLNdà

\

≈)¸/* component flags */°dONLNdü
`
ƒ(
6~unsigned hex longint°dONLNd¥
Ã

S)lkAnyComponentFlagsMask = 0;°dONLNd–

\

fi)ê/* component flags Mask */°dONLNdÏ
`
$∞(
@~literal longint;°dONLNd


\
$
ß)¸/* Code Type */°dONLNd
#`
.à(
J~integer;°dONLNd 
#
\
.
ù)¸
/* Code ID */°dONLNd/
-`
8∞(
T~literal longint;°dONLNdD
-
\
8
ß)¸/* Name Type */°dONLNdU
7`
Bà(
^~integer;°dONLNdc
7
\
B
ù)¸
/* Name ID */°dONLNdr
A`
L∞(
h~literal longint;°dONLNdá
A
\
L
ß)¸/* Info Type */°dONLNdò
K`
Và(
r~integer;°dONLNd¶
K
\
V
ù)¸
/* Info ID */°dONLNdµ
U`
`∞(
|~literal longint;°dONLNd 
U
\
`
ß)¸/* Icon Type */°dONLNd€
_`
jà(
Ü~integer;°dONLNdÈ
_
\
j
ù)¸
/* Icon ID */°dONLNd˜
i<
t»(
êZ#if UseExtendedThingResource°dONLNd
s`
~…+$
unsigned hex longint;°dONLNd.
s
\
~
fi)¸/* version of Component */°dONLNdJ
}`
àà(
§~longint;°dONLNdX
}
\
à
Ë)¸/* flags for registration */°dONLNdv
á`
íà(
Æ~integer;°dONLNdÑ
á
\
í
œ)¸/* resource id of Icon °dONLNd£
ë
\
ú
ò*
   Family */°dONLNd±
õ`
¶
7(
¬~+longint = $$CountOf(ComponentPlatformInfo);°dONLNdfi
•`
∞

*
"wide array ComponentPlatformInfo {°dONLNd
Ø`
∫‚*
    unsigned hex longint; °dONLNd 
Ø
\
∫
 )¸/* component  flags */°dONLNd8
π`
ƒƒ(
‡~    literal longint;°dONLNdQ
π
\
ƒ
ß)¸/* Code Type */°dONLNdb
√`
Μ(
Í~    integer;°dONLNdt
√
\
Œ
ù)¸
/* Code ID */°dONLNdÉ
Õ`
ÿ
U(
Ù~1    integer platform68k = 1, platformPowerPC = 2;°dONLNdµ
Õ
\
ÿ
ª)¸/* platform type */°dONLNd 
◊`
‚~(
˛~    };°dONLNd—
·<
ÏZ(Z#endif°dONLNdÿ
Î<
ˆF*
};°dONLNd€
ˇ<
™*/* MPW C interfaces */°dONLNdÚ<Z*enum {°dONLNd˘<(»*
#define gestaltComponentMgr °dONLNd(
)¥'cpnt'°dONLNd
8(
ø)H/* Component Mgr version */°dONLNd:1<<·(XZ!#define gestaltQuickTimeFeatures °dONLNd\1<
)¥'qtrs'°dONLNdd1
8<
∞)H/* QuickTime features */°dONLNd~;`F

(b~"gestaltPPCQuickTimeLibPresent = 0,°dONLNd¢;
8F
›)ÿ!/* PowerPC QuickTime glue library°dONLNdÀE
8P
à*
   is present */°dONLNd‹c<nı(äZ%#define gestaltSysArchitecture 'sysa'°dONLNdc
8n
ÿ)¸ /* Native System Architecture */°dONLNd%m`x´(î~gestalt68k = 1,°dONLNd8m
8x
›)ÿ!/* Motorola MC68K architecture */°dONLNd[w`Çø(û~gestaltPowerPC = 2,°dONLNdrw
8Ç
Œ)ÿ/* IBM PowerPC architecture */°dONLNdíã`ñ
•(≤~A/* componentRegisterFlags flags for ComponentResourceExtension */°dONLNd’ï`†”*
componentDoAutoVersion °dONLNdÓï
†
A)¥    = (1<<0),°dONLNd˘ü`™›(Δ~componentWantsUnregister °dONLNdü
™
A)¥    = (1<<1), ’X’

(ÎZQT 05 - Component Manager 3.0(Î
˙11)
 of 12(
ZM.QT.Component Manager 3.0ˇ
◊#ˇˇˇˇˇ#◊

IR,Palatino

.+6-Macintosh Technical Notes 040
˘,
Courier
    °dONLNd<·+$!componentAutoVersionIncludeFlags °dONLNd"
)¥    = (1<<2),°dONLNd-<'“(CZcomponentHasMultiplePlatforms °dONLNdL'
)¥= (1<<3)°dONLNdU&1"(M6};°dONLNdX:E§*struct ComponentPlatformInfo°dONLNduDO*

{°dONLNdxN<YP+$
long°dONLNdN®YÛ)lcomponentFlags;°dONLNdèN
Y
å)l/* flags of Component */°dONLNd©X<c}(Z
ResourceSpec °dONLNd∏X®c⁄)l
component;°dONLNdƒX
c
π)l!/* resource where Component code °dONLNdÏb
m
Z*
   is found */°dONLNd¸l<wU(ìZshort°dONLNd
l®wÈ)l
platformType;°dONLNd
l
w
ë)l/* gestaltSysArchitecture°dONLNd
5v
Å
P*
   result */°dONLNd
BÄã"(ß6};°dONLNd
Eäï
?*
;typedef struct ComponentPlatformInfo ComponentPlatformInfo;°dONLNd
Åû©©*struct ExtComponentResource {°dONLNd
†®<≥†+$
ComponentDescription°dONLNd
µ®®≥∑)lcd;°dONLNd
ª®
≥
•)l/* Registration parameters */°dONLNd
⁄≤<Ω}(ŸZ
ResourceSpec °dONLNd
Ë≤ÑΩ∂)H
component;°dONLNd
ı≤
Ω
π)ê!/* resource where Component code °dONLNdº
«
Z*
   is found */°dONLNd-Δ<—x(ÌZResourceSpec°dONLNd:ΔÑ— )HcomponentName;°dONLNdJΔ
—
ñ)ê/* name string resource */°dONLNdf–<€x(˜ZResourceSpec°dONLNds–Ñ€ )HcomponentInfo;°dONLNdÉ–
€
ñ)ê/* info string resource */°dONLNdü⁄<Âx(

ZResourceSpec°dONLNd¨⁄Ñ )HcomponentIcon;°dONLNdº⁄
Â
s)ê/* icon resource */°dONLNd—Ó<˘
"(
Z./* new data for Component Manager version 3 */°dONLNd
¯<
P*
long°dONLNd¯Ñ
Ÿ)HcomponentVersion;°dONLNd¯


ñ)ê/* version of Component */°dONLNd6
<

P(
)Zlong°dONLNd<
Ñ

˜)HcomponentRegisterFlags;°dONLNdT




†)ê/* flags for registration */°dONLNdr
<
U(
3Zshort°dONLNdy
Ñ
Ë)HcomponentIconFamily;°dONLNdè



¥)ê /* resource id of Icon Family */°dONLNd±
<
!P(
=Zlong°dONLNd∑
Ñ
!¢)Hcount;°dONLNd¡


!
Ø)ê/* elements in platformArray */°dONLNd‚
 <
+ˇ(
GZ'ComponentPlatformInfo platformArray[1];°dONLNd

*
5"(
Q6};°dONLNd

4
?
5*
9typedef struct ExtComponentResource ExtComponentResource;,Times

°dONLNdG
Z
fÇ*'Further Reference: 
Ö4
Ö
˘°dONLNdZ
g*
s.+

•°dONLNd\
g<
s@)
I°dONLNd]
g@
s
)'nside Macintosh: More Macintosh Toolbox°dONLNdÑ
g

s
y)À (Component Manager)°dONLNdô
s*
.(
õH
•°dONLNdõ
s<

%))Inside Macintosh: PowerPC System Software°dONLNdƒ
s
%

w)È
 (Mixed Mode °dONLNd—
s
w

⁄)RManager and Code°dONLNd‚
<
ãô(
ßZFragment Manager)°dONLNdÙ
ã*
ó.(
≥H
•°dONLNdˆ
ã<
ó
 )LMacintosh Technical Note, Drawing Icons the System 7 Way (M.IM.IconDrawing). fi4fi
˘

(Û612)
 of 12(Û
qQT 05 - Component Manager 3.0+
M.QT.ComponentManager3.0ˇ